<!DOCTYPE html>
<HTML lang="en">
<HEAD>
    <title> The BBX_Options object </title>
    <meta charset="UTF-8">
        
    <link href="prism.css" rel="stylesheet">
<script src="microlight.js"> </script>
<script src="prism.js"> </script>
<style>
.microlight {
    font-family : monospace;
    white-space : pre;
    background-color : white;
}
    
BODY {
    width:50em;
    margin-left:5em;
    background-color:#c0c0ff;
}

P {
   width : 50em;
}

pre {
   background-color:white;
}
</style>
</HEAD>
<BODY>
    <script src="prism.js"></script>
    <A href ="https://github.com/MalcolmMcLean"> <IMG src = "Cartoon_Owl_clip_art.png" alt="Malcolm's github site">  </A>
    <A href ="index.html"> <IMG src = "babyxrc_logo.svg" alt="Baby X Resource compiler" width = "64" height = "62"> </A>
    <A href ="BabyXFS.html"> <IMG src = "BabyXLogos/baby-x-fs-logo.svg" alt="Baby X FileSystem" width = "64" height = "62"> </A>
    &nbsp;&nbsp;
    <IMG src = "BabyXLogos/babyxfs-banner.svg" width = "256" height = "62" alt = "Baby X FS banner">
<H1>The BBX_Options object </H1>
<P>
The Baby X Options object, BBX_Options, is a Baby X object designed to parse commandline options easily and automatically report errors.. The object is extremly easy for programmers to use and is lightweight, a single file, so a "baby" options parser in the spirit of Baby X. It is part of the <A href = "BabyXFS.html">BabyXFS</A> or Baby X FileSystem project, whch is a project designed to allow Baby X user to mount directories.
</P>

<P>
The BBX_Options option parser is designed to allow calling programmers
to parse options cleanly and easily in the main() function,
taking most of the error checking and parse logic out of
the calling program.
</P>

<H2> Public functions </H2>

    <H3>bbx_options</H3>
<P>
<pre><code class="language-c">
    BBX_Options *bbx_options(int argc, char **argv, char *flags);
</code>
</pre>
<P>
Start the options parser. Pass it argc and argv from the arguments to
main, and a list of single character flags e.g. "lbw" for options
"-l", "-b", -"w". You don't need to pass non-single character options.
If there are no single character flag options, pass NULL rather than
the empty string.
</P>

<H3> bbx_options_kill</H3>
<pre><code class="language-c">
    void bbx_options_kill(BBX_Options *opt);
</code></pre>

<P>
Destroys the options object.
</P>
<H3> bbx_options_get </H3>

<pre><code class="language-c">
    int options_get(BBX_Options *opt, char *name, char *fmt, ...);
</code></pre>

<P>
    Get an option.
</P>
<pre>
    name - "-option -o -opt -OPT" - list of alternative names
    fmt - "%d%32s%f" - list of option parameters
    %d - an integer - argument int *
    %f - a real - argument double *
    %s - a string - argument char *
    strings should take a buffer length qualifer (default 256)
</pre>

<P>
Returns the number of arguments consumed. However it's not normally
necessary to check for errors. Call bbx_options_error after parsing
all the options.
</P>

<H3>bbx_options_error</H3>

<pre><code class="language-c">
    int bbx_options_error(BBX_Options *opt, char *errormessage, int Nerror);
</code></pre>

<P>
Returns non-zero if the options parser encountered an error. It then
writes an human-readable error report to the error buffer. The errormessage
can be null if you don't want to report the error to the user.
</P>
<H3>bbx_options_Nargs</H3>
<pre><code class="language-c">
    int bbx_options_Nargs(BBX_Options *opt);
</code></pre>
<P>
This gets the number of arguments left after otions have been parsed.
</P>
<H3>bbx_options_arg</H3>

<pre><code class="language-c">
    char *bbx_options_arg(BBX_Options *opt, int index);
</code></pre>

<P>
Retrieves the commandline non-option argument (most frequently file
names). You must call after parsing the options.
</P>
<H2>Example Usage</H2>

<pre><code class="language-c">
    int main(int argc, char *argv)
    {
       char errormessage[1024];
       // defaults if option not provided by user
       int width = 256; // an integer ootion
       char name[32] = "Fred"; // a string option
       double quality = 0.0; // a floating point option
       char *filename; // a file argument

       BBX_Options *opt = bbx_options(argc, argv, NULL);
       if (!opt)
          exit(EXIT_FAILURE);

       // if the option is in fact required, check the return value
       bbx_options_get(opt, "-width -w", "%d", &width);
       bbx_options_get(opt, "-name", "%32s", name);
       bbx_options_get(opt, "-quality -q", "%f", &quality);

       if (bbx_options_Nargs != 1)
           usage();          // user hasn't entered a file name

        filename = bbx_options_arg(opt, 0);

       if (bbx_options_error(opt, errormesssage, 1024))
          exit(EXIT_FAILURE);  // error message should be anough to tell
             // user what is wrong.
     
        bbx_options_kill(opt);
        opt = 0;

        if (width &lt;= 0)
           fprintf(stderr, "width must be positive\n"); // It won't sanity
              // test options for you

        dowork(filename, width, name, quality);

        return 0;
    }
</code></pre>

<P>
It's very clean and easy to use.
</P>

</BODY> </HTML>

